Skip to content

nginx, Compose and the web deploy learn the selector commentsShadow - #3400

Merged
colinmegill merged 4 commits into
edgefrom
nginx/comments-shadow
Nov 12, 2026
Merged

colinmegill merged 4 commits into
edgefrom
nginx/comments-shadow

Conversation

@colinmegill

Copy link
Copy Markdown
Member

Observable changes: none while RUST_API_ROUTES does not name commentsShadow, as nowhere does. For every selection the previous renderer accepts, nginx renders the same bytes; the shadow service starts with the same image, limits and settings plus three environment entries that are inert while its comment switch is empty; the deploy's validation gives the same verdicts, and additionally requires that the shadow service has no comment observer when the name is not selected.

What it adds, for when the name is selected:

  • nginx. commentsShadow renders the mirror of POST /api/v3/comments to the shadow service from the vote shadow's own templates, with the name and the path replaced: Node answers every comment exactly as before, with one added request header (X-Request-Id), and a copy goes to polis-api-shadow. The access line of a shadowed comment and the two JSON lines are the vote shadow's formats. With the comment read route selected too, the POST diversion is inserted into that route's location. Both shadows together is the ordinary selection.
  • A rate for the copies. One limit_req zone, used in the copy's location only: 2 a second on a box and 4 more at once. A copy over the rate ends there with 429; the request Node answers is never counted, delayed or refused.
  • Compose. The shadow service always has the comment observer's rate and database; its switch is a literal empty value, so neither the file nor the env document can turn it on.
  • The deploy. after_install.sh derives the switch from the route list, writes it into the Compose override it generates, checks the composed value before it replaces anything, and starts the shadow service when either shadow is selected. validate_service.sh requires the shadow's /health to show the comment observer (observe mode, never enabled, its two read-only pools, room for 8 and 64, at most 6 a second) exactly when commentsShadow is selected. commentsShadow with postComments, the name reserved for a route that writes comments, is refused by both.

What the mirror does to a comment POST: nginx reads the whole body before it contacts Node. For a body that arrives whole, as every real comment does, Node has the request no later than before; a slow body reaches Node when its last byte has arrived; a body too long to hold in memory, which is never a valid comment and never copied, goes through a temporary file. The reply is the same bytes in every case, and with the shadow service answering, absent, silent, slow, answering 404 or answering 500.

Order: deploy a release that knows the name before the name is selected, and remove the name before deploying an older release. A renderer that does not know a name refuses the whole list and sends every route to Node while that release's validation still passes (file-server/nginx/ROUTING.md, "The comment shadow").

Tests: the routing suite checks each rendered location line by line against the vote shadow's; the behaviour suite runs the comment shadow behind the production nginx image in nine modes of the shadow stand-in, both shadows together, reads on the comment path, the rate, and bodies from 180 bytes to the largest nginx and Node accept; shadow-stack.sh runs real comments through nginx to the real Node server with the real shadow service under docker-compose.yml, started without the switch, with it, paused and stopped, and compares Node's replies byte for byte; the hook, validation and health predicate tests cover every pairing of the route list with what the service reports.

No schema change, no migration, no Node change, no Rust change.

Order matters when the name is ever selected: this release first, the secret second. A release without this change deployed while the route list names commentsShadow refuses the whole list, so every Rust route goes back to Node and the vote copies stop, while that release's validation still passes; "released" means the web deployment group's last successful revision, since an Auto Scaling launch deploys that. ROUTING.md says so.

Known limits, each a follow-up and none affecting a person: a copy carries no query string, so a comment whose parameters travelled there is observed without them (the repository's clients use the body); with a shadow selected nginx buffers every POST to the mirrored path before proxying (as it has for votes since the vote shadow), including bodies that will not be copied.

The hosted polis-api job's time limit goes from 40 to 60 minutes: the new behaviour and stack tests add about ten minutes to a job that ran in about thirty.

Stacked on the pull request that adds the comments observe mode (PR #3398); the diff shown is this change alone. Reviewed independently; the reviewer re-derived the no-change result (971 route lists render byte-identical nginx) and reproduced the rollback behaviour.

🤖 Generated with Claude Code

colinmegill and others added 3 commits November 10, 2026 22:28
…ndler, switched off and never served

The handler admits an ordinary comment from an existing participant and hands
everything else back to Node before anything is written, each under a named
reason. The comment and its author's vote are written in one transaction; a
write PostgreSQL provably refused is handed back to Node. A conversation with
strict moderation reaches a typed decision the live path cannot write. The
comment's text is held in a type that cannot be printed. Off unless
POLIS_API_POST_COMMENTS=1; no nginx route sends a comment to this server.

Co-Authored-By: Claude <noreply@anthropic.com>
…stener that serves two mirrored routes

Built only by the shadow role when POLIS_API_POST_COMMENTS=observe, which nothing
sets. The observer runs the live handler's own checks and admission statement on
read-only pools, says what the live handler would do with each copied comment,
reads back what Node stored and prints one line of classes: no conversation,
comment or participant number, no text. The shadow listener serves its mirrored
routes from a table, each with its own lane, bound, rate bucket and pools; the
vote observations are unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
When RUST_API_ROUTES names commentsShadow, nginx copies each POST
/api/v3/comments to the read-only shadow service under its own rate limit, the
deploy hook passes the shadow service its comment switch through the Compose
override it already writes, and validation requires the shadow's health to
report the comment observer exactly. Nothing names it: for every existing
selection nginx renders the same bytes and validation gives the same verdicts.

Co-Authored-By: Claude <noreply@anthropic.com>
The change this branch was stacked on is now on edge as one squashed commit.
Git sees the squashed files and the branch's copies as two separate additions;
each such file is resolved to the side that changed it since the old base (no
file was changed on both sides). The result differs from edge by exactly this
branch's own change.
@github-actions

Copy link
Copy Markdown
Contributor

Delphi Coverage Report

File Stmts Miss Cover
polismath/init.py 2 0 100%
polismath/benchmarks/bench_pca.py 128 107 16%
polismath/benchmarks/bench_repness.py 81 65 20%
polismath/benchmarks/bench_update_votes.py 38 28 26%
polismath/benchmarks/benchmark_utils.py 34 0 100%
polismath/components/init.py 1 0 100%
polismath/components/config.py 165 70 58%
polismath/conversation/init.py 2 0 100%
polismath/conversation/conversation.py 1293 264 80%
polismath/conversation/group_vote_counts.py 38 2 95%
polismath/conversation/manager.py 131 42 68%
polismath/database/init.py 1 0 100%
polismath/database/dynamodb.py 392 176 55%
polismath/database/postgres.py 414 95 77%
polismath/delphi_storage/init.py 1 0 100%
polismath/delphi_storage/codec.py 295 22 93%
polismath/delphi_storage/embedding_spool.py 58 6 90%
polismath/delphi_storage/golden_corpus.py 60 9 85%
polismath/delphi_storage/import_report.py 51 3 94%
polismath/delphi_storage/legacy_import.py 171 16 91%
polismath/delphi_storage/postgres.py 49 22 55%
polismath/delphi_storage/production_import.py 612 131 79%
polismath/delphi_storage/resource.py 179 32 82%
polismath/delphi_storage/scan_pacing.py 77 0 100%
polismath/delphi_storage/writer.py 196 13 93%
polismath/empty_output.py 29 2 93%
polismath/engine_adapter.py 317 265 16%
polismath/job_child/init.py 364 51 86%
polismath/job_child/census.py 74 9 88%
polismath/job_child/input_bundle.py 101 7 93%
polismath/pca_kmeans_rep/init.py 5 0 100%
polismath/pca_kmeans_rep/clusters.py 257 38 85%
polismath/pca_kmeans_rep/corr.py 98 17 83%
polismath/pca_kmeans_rep/group_k_smoother.py 28 0 100%
polismath/pca_kmeans_rep/legacy_kmeans.py 197 7 96%
polismath/pca_kmeans_rep/pca.py 162 19 88%
polismath/pca_kmeans_rep/repness.py 226 5 98%
polismath/poller/init.py 4 0 100%
polismath/poller/admission.py 318 15 95%
polismath/poller/backfill.py 936 32 97%
polismath/poller/capacity.py 485 27 94%
polismath/poller/capacity_queue.py 248 13 95%
polismath/poller/coordinator_bridge.py 317 317 0%
polismath/poller/math_writer.py 113 3 97%
polismath/poller/promotion.py 112 4 96%
polismath/poller/readiness.py 368 13 96%
polismath/poller/rebuild_child.py 133 5 96%
polismath/poller/service.py 756 54 93%
polismath/poller/worker_pool.py 140 0 100%
polismath/queue/executor.py 221 111 50%
polismath/regression/init.py 4 0 100%
polismath/regression/clojure_comparer.py 188 20 89%
polismath/regression/comparer.py 891 640 28%
polismath/regression/datasets.py 126 27 79%
polismath/regression/recorder.py 36 27 25%
polismath/regression/utils.py 130 85 35%
polismath/replay/init.py 2 0 100%
polismath/replay/attribution_capture.py 49 0 100%
polismath/replay/axis_continuity.py 347 24 93%
polismath/replay/certify.py 999 59 94%
polismath/replay/crosslang.py 128 2 98%
polismath/replay/decision_ties.py 51 8 84%
polismath/replay/diagnostics.py 50 7 86%
polismath/replay/driver.py 73 1 99%
polismath/replay/dsn_admission.py 36 1 97%
polismath/replay/equiv_query.py 10 0 100%
polismath/replay/event_ingress.py 95 1 99%
polismath/replay/fixture_bundle.py 815 62 92%
polismath/replay/fixture_config.py 266 11 96%
polismath/replay/fixture_extract.py 285 12 96%
polismath/replay/fixture_generate.py 103 1 99%
polismath/replay/fixture_samples.py 157 14 91%
polismath/replay/fixture_selection.py 119 0 100%
polismath/replay/fixture_survey.py 147 11 93%
polismath/replay/legacy_pca.py 29 17 41%
polismath/replay/polarity.py 319 25 92%
polismath/replay/poller_equiv.py 776 99 87%
polismath/replay/prodclone.py 193 2 99%
polismath/replay/real_data.py 146 10 93%
polismath/replay/schedule.py 205 10 95%
polismath/replay/served_math.py 159 4 97%
polismath/replay/shard_bench.py 189 65 66%
polismath/replay/stagecompare.py 890 161 82%
polismath/replay/stages.py 256 40 84%
polismath/replay/stepcompare.py 86 1 99%
polismath/replay/store.py 120 11 91%
polismath/replay/tie_capture.py 107 19 82%
polismath/replay/types.py 58 6 90%
polismath/run_math_pipeline.py 284 93 67%
polismath/tools/engine_rebuild.py 230 11 95%
polismath/types.py 6 0 100%
polismath/utils/cli_flags.py 15 0 100%
polismath/utils/clj_hash.py 44 0 100%
polismath/utils/env_flags.py 13 0 100%
polismath/utils/general.py 63 39 38%
polismath/utils/output_profile.py 66 2 97%
polismath/utils/serialization.py 10 5 50%
polismath/utils/vote_convention.py 159 5 97%
umap_narrative/700_datamapplot_for_layer.py 514 470 9%
umap_narrative/701_static_datamapplot_for_layer.py 310 310 0%
umap_narrative/702_consensus_divisive_datamapplot.py 435 275 37%
umap_narrative/801_narrative_report_batch.py 657 209 68%
umap_narrative/803_check_batch_status.py 268 148 45%
umap_narrative/llm_factory_constructor/init.py 2 0 100%
umap_narrative/llm_factory_constructor/model_provider.py 232 106 54%
umap_narrative/narrative_data.py 178 55 69%
umap_narrative/numerical_stages.py 80 14 82%
umap_narrative/polismath_commentgraph/init.py 1 0 100%
umap_narrative/polismath_commentgraph/cli.py 268 268 0%
umap_narrative/polismath_commentgraph/core/init.py 3 3 0%
umap_narrative/polismath_commentgraph/core/clustering.py 108 108 0%
umap_narrative/polismath_commentgraph/core/embedding.py 104 104 0%
umap_narrative/polismath_commentgraph/lambda_handler.py 219 219 0%
umap_narrative/polismath_commentgraph/schemas/init.py 2 0 100%
umap_narrative/polismath_commentgraph/schemas/dynamo_models.py 80 6 92%
umap_narrative/polismath_commentgraph/tests/conftest.py 17 17 0%
umap_narrative/polismath_commentgraph/tests/test_clustering.py 74 74 0%
umap_narrative/polismath_commentgraph/tests/test_embedding.py 55 55 0%
umap_narrative/polismath_commentgraph/tests/test_storage.py 87 87 0%
umap_narrative/polismath_commentgraph/utils/init.py 9 7 22%
umap_narrative/polismath_commentgraph/utils/converter.py 283 50 82%
umap_narrative/polismath_commentgraph/utils/group_data.py 332 279 16%
umap_narrative/polismath_commentgraph/utils/storage.py 609 481 21%
umap_narrative/reset_conversation.py 162 53 67%
umap_narrative/run_pipeline.py 355 203 43%
umap_narrative/topic_naming.py 148 11 93%
Total 25600 7367 71%

@colinmegill
colinmegill merged commit 6d730e7 into edge Nov 12, 2026
72 of 75 checks passed
@colinmegill
colinmegill deleted the nginx/comments-shadow branch November 12, 2026 04:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant